Overview

This PR adds an injectable SdkLogger to ProtocolOptions, threads it through Protocol, Client, and McpServer, and routes existing console.* SDK diagnostics (capability-gating debug messages, tool-name validation warnings, zod-fallback warnings) through it. It exports the SdkLogger type from the core public exports, adds a changeset, prose documentation in docs/client.md and docs/server.md, a sourced example in examples/client/src/clientGuide.examples.ts, and focused tests for the client, tool-name, prompt-conversion, and zod-fallback paths. The latest commit also addresses both items raised in my prior review: promptArgumentsFromStandardSchema now accepts and forwards a logger (with the prompts/list call site passing this._logger), and prose documentation for the option was added.

Security risks

None identified. The logger is a user-supplied callback object invoked only with diagnostic strings via optional chaining; it does not handle credentials, network input, or auth flows. The default remains console, preserving existing behavior for callers that don't opt in.

Level of scrutiny

Moderate. The mechanical changes (replacing console.warn/console.debug with this._logger.*?.() and threading a defaulted parameter) are low risk and well covered by the new tests, which also assert that console is no longer hit when a custom logger is configured. However, the PR introduces a new public API surface — a logger field on ProtocolOptions and a newly exported SdkLogger type — and this repository's conventions place the burden of proof on additions to the public API. Whether the shape (partial logger with all-optional methods, no level filtering, named SdkLogger, attached to ProtocolOptions rather than a narrower options type) is the right long-term design is a maintainer judgment call, so I'm not shadow-approving.

Other factors

The change has a concrete motivating issue (#1262), the changeset correctly marks core/client/server as minor, and existing behavior is unchanged when no logger is provided. The test coverage is reasonable: client capability-gating debug routing, tool-name warning routing, prompt argsSchema conversion routing, and the zod-fallback path all assert both the custom logger call and the absence of console output. No unresolved reviewer comments remain on the thread.

Overview

This PR adds an injectable SDK diagnostics logger: a new logger field on ProtocolOptions (consumed by Protocol, Client, and McpServer), a new SdkLogger type exported from the public surface of core-internal, and routing of existing console.* diagnostics (client capability-gating debug messages, tool-name validation warnings, zod JSON-schema fallback warnings) through that logger. It also adds prose docs in docs/client.md and docs/server.md, a sourced example, focused tests in all three packages, and a changeset bumping core-internal/client/server as minor.

Status of prior feedback

All three issues raised on earlier revisions are resolved in the current diff: the changeset frontmatter now lists @modelcontextprotocol/core-internal instead of the schemas-only core package; promptArgumentsFromStandardSchema now accepts and forwards a logger and McpServer passes this._logger at the prompts/list call site (with a regression test); and prose documentation plus an example were added. A grep of the modified packages shows no remaining un-routed console.* diagnostics in scope (the fetch-logging middleware has its own configurable RequestLogger and is unrelated).

Security risks

None identified. The logger is a passive sink for diagnostic strings; no auth, crypto, or transport behavior changes. The only minor consideration is that user-supplied logger callbacks now run inside SDK code paths, but they are invoked with optional chaining and a throwing logger would surface like any handler error.

Level of scrutiny

The implementation is small and well-tested, but this is a deliberate public API addition on a repo whose review conventions put the burden of proof on additions and ask for design-level sign-off first. There is also an unanswered maintainer comment referencing the earlier exploration in PR #1034 (stdio caveats, RFC5424/syslog level alignment), which bears directly on whether the minimal four-method SdkLogger shape is the right long-term surface. That design call belongs to a human maintainer, so I am deferring rather than approving despite finding no correctness issues.

Other factors

Test coverage is good (client logger routing, tool-name warning routing, prompt argsSchema fallback routing, direct standardSchema fallback test), and the docs additions correctly distinguish SDK-internal diagnostics from MCP protocol logging. The codemod versions.ts regeneration matches the corrected changeset targets.

Overview

This PR adds an injectable SDK logger: a new SdkLogger type in core-internal/src/shared/logger.ts, a logger field on ProtocolOptions (consumed by Protocol/Client/Server/McpServer) and on CreateMcpHandlerOptions, and it routes existing console.debug/console.warn SDK diagnostics (client capability messages, x-mcp-header exclusion warnings, tool-name validation warnings, zod-fallback warnings, the responseMode:'json' warning) through the configured logger with console as the default. Tests are added in the client, core-internal, and server packages covering each migrated call site.

Security risks

None of consequence — the change only affects where diagnostic strings are emitted. The logger is user-supplied and called with SDK-generated messages; there is no injection surface, no auth or transport behavior change, and defaults preserve existing console output.

Level of scrutiny

The implementation is mechanical and well-tested, but it adds new public API surface (the exported SdkLogger type and the logger option on two options interfaces across three published packages). Per this repository's conventions, new public API additions carry a burden of proof and should get maintainer review of the design (naming, whether all-optional-methods partial-logger semantics are the right shape, whether the option belongs on CreateMcpHandlerOptions too), so this is not a candidate for auto-approval despite the code being straightforward.

Other factors

All issues flagged in previous review rounds have been addressed in the current diff: the changeset now targets @modelcontextprotocol/core-internal, promptArgumentsFromStandardSchema accepts and forwards the logger, the client-side x-mcp-header exclusion warning uses this._logger, and createMcpHandler accepts a logger option — each with a corresponding test. The remaining gap is prose documentation: no docs/ page describes the new option or the partial-logger semantics (all methods optional), which the repo checklist asks for on new features. The bug hunting system found no bugs in the current revision.